home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 21 / AACD 21.iso / AACD / Utilities / Ghostscript / src / gscspace.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-01-01  |  16.4 KB  |  429 lines
  1. /* Copyright (C) 1991, 2000 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of AFPL Ghostscript.
  4.   
  5.   AFPL Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author or
  6.   distributor accepts any responsibility for the consequences of using it, or
  7.   for whether it serves any particular purpose or works at all, unless he or
  8.   she says so in writing.  Refer to the Aladdin Free Public License (the
  9.   "License") for full details.
  10.   
  11.   Every copy of AFPL Ghostscript must include a copy of the License, normally
  12.   in a plain ASCII text file named PUBLIC.  The License grants you the right
  13.   to copy, modify and redistribute AFPL Ghostscript, but only under certain
  14.   conditions described in the License.  Among other things, the License
  15.   requires that the copyright notice and this notice be preserved on all
  16.   copies.
  17. */
  18.  
  19. /*$Id: gscspace.h,v 1.5 2000/09/19 19:00:27 lpd Exp $ */
  20. /* Client interface to color spaces */
  21.  
  22. #ifndef gscspace_INCLUDED
  23. #  define gscspace_INCLUDED
  24.  
  25. #include "gsmemory.h"
  26.  
  27. /*
  28.  * The handling of color spaces in the graphic library is somewhat
  29.  * awkward because of historical artifacts.
  30.  *
  31.  * The PostScript Level 1 (DeviceGray/RGB) color spaces, and the "Level
  32.  * 1 1/2" DeviceCMYK space, have no associated parameters.  Therefore,
  33.  * they can be represented as simple objects (just a pointer to a type
  34.  * vector containing procedures and parameters).  This was the original
  35.  * design.
  36.  *
  37.  * PostScript Level 2 and LanguageLevel 3 add two new kinds of color spaces:
  38.  * color spaces with parameters (CIEBased and DevicePixel spaces), and
  39.  * compound color spaces (Indexed, Separation, Pattern, and DeviceN spaces),
  40.  * which parameters that include specifying an alternate or underlying color
  41.  * space.  To handle these spaces, we extended the original design to store
  42.  * scalar parameters (i.e., parameters other than the complex color
  43.  * transformation data for CIEBased spaces, the lookup table for Indexed
  44.  * spaces, and the list of component names for DeviceN spaces) in-line in
  45.  * the color space object.  For compound spaces, this requires storing a
  46.  * color space in-line inside another color space, which is clearly
  47.  * impossible.  Therefore, we defined a generality hierarchy for color
  48.  * spaces:
  49.  *
  50.  *      - Base spaces (DeviceGray/RGB/CMYK/Pixel and CIEBased),
  51.  *      whose parameters (if any) don't include other color spaces.
  52.  *
  53.  *    - Direct spaces (base spaces + Separation and DeviceN), which
  54.  *    may have a base space as an alternative space.
  55.  *
  56.  *      - Paint spaces (direct spaces + Indexed), which may have a
  57.  *      direct space as the underlying space.
  58.  *
  59.  *      - General spaces (paint spaces + Pattern), which may have a
  60.  *      paint space as the underlying space.
  61.  *
  62.  * With this approach, a general space can include a paint space stored
  63.  * in-line; a paint space (either in its own right or as the underlying
  64.  * space of a Pattern space) can include a direct space in-line; and a
  65.  * direct space can include a base space in-line.
  66.  *
  67.  * Note that because general, paint, direct, and base spaces are
  68.  * (necessarily) of different sizes, assigning (copying the top object of)
  69.  * color spaces must take into account the actual size of the color space
  70.  * being assigned.  In principle, this also requires checking that the
  71.  * source object will actually fit into the destination.  Currently we rely
  72.  * on the caller to ensure that this is the case; in fact, the current API
  73.  * (gs_cspace_init and gs_cspace_assign) doesn't even provide enough
  74.  * information to make the check.
  75.  *
  76.  * In retrospect, we might have gotten a simpler design without significant
  77.  * performance loss by always referencing underlying and alternate spaces
  78.  * through a pointer; however, at this point, the cost and risk of changing
  79.  * to such a design are too high.
  80.  *
  81.  * There are two aspects to memory management for color spaces: managing
  82.  * the color space objects themselves, and managing the non-scalar
  83.  * parameters that they reference (if any).
  84.  *
  85.  *      - Color space objects per se have no special management properties:
  86.  *      they can be allocated on the stack or on the heap, and freed by
  87.  *      scope exit, explicit deallocation, or garbage collection.
  88.  *
  89.  *      - Separately allocated (non-scalar) color space parameters are
  90.  *      managed by reference counting.  Currently we do this for the
  91.  *      CIEBased spaces, and for the first-level parameters of Indexed and
  92.  *      Separation spaces: clients must deal with deallocating the other
  93.  *      parameter structures mentioned above, including the Indexed lookup
  94.  *      table if any. This is clearly not a good situation, but we don't
  95.  *      envision fixing it any time soon.
  96.  *
  97.  * Here is the information associated with the various color space
  98.  * structures.  Note that DevicePixel, DeviceN, and the ability to use
  99.  * Separation or DeviceN spaces as the base space of an Indexed space
  100.  * are LanguageLevel 3 additions.  Unfortunately, the terminology for the
  101.  * different levels of generality is confusing and inconsistent for
  102.  * historical reasons.
  103.  *
  104.  * For base spaces:
  105.  *
  106.  * Space        Space parameters                Color parameters
  107.  * -----        ----------------                ----------------
  108.  * DeviceGray   (none)                          1 real [0-1]
  109.  * DeviceRGB    (none)                          3 reals [0-1]
  110.  * DeviceCMYK   (none)                          4 reals [0-1]
  111.  * DevicePixel  depth                           1 int [up to depth bits]
  112.  * CIEBasedDEFG dictionary                      4 reals
  113.  * CIEBasedDEF  dictionary                      3 reals
  114.  * CIEBasedABC  dictionary                      3 reals
  115.  * CIEBasedA    dictionary                      1 real
  116.  *
  117.  * For non-base direct spaces:
  118.  *
  119.  * Space        Space parameters                Color parameters
  120.  * -----        ----------------                ----------------
  121.  *
  122.  * Separation   name, alt_space, tint_xform     1 real [0-1]
  123.  * DeviceN      names, alt_space, tint_xform    N reals
  124.  *
  125.  * For non-direct paint spaces:
  126.  *
  127.  * Space        Space parameters                Color parameters
  128.  * -----        ----------------                ----------------
  129.  * Indexed      base_space, hival, lookup       1 int [0-hival]
  130.  *
  131.  * For non-paint spaces:
  132.  *
  133.  * Space        Space parameters                Color parameters
  134.  * -----        ----------------                ----------------
  135.  * Pattern      colored: (none)                 dictionary
  136.  *              uncolored: base_space dictionary + base space params */
  137.  
  138. /*
  139.  * Define color space type indices.  NOTE: PostScript code (gs_res.ps,
  140.  * gs_ll3.ps) and the color space substitution code (gscssub.[hc] and its
  141.  * clients) assumes values 0-2 for DeviceGray/RGB/CMYK respectively.
  142.  */
  143. typedef enum {
  144.  
  145.     /* Supported in all configurations */
  146.     gs_color_space_index_DeviceGray = 0,
  147.     gs_color_space_index_DeviceRGB,
  148.  
  149.     /* Supported in extended Level 1, and in Level 2 and above */
  150.     gs_color_space_index_DeviceCMYK,
  151.  
  152.     /* Supported in LanguageLevel 3 only */
  153.     gs_color_space_index_DevicePixel,
  154.     gs_color_space_index_DeviceN,
  155.  
  156.     /* Supported in Level 2 and above only */
  157.     /* DEC C truncates identifiers at 32 characters, so.... */
  158.     gs_color_space_index_CIEDEFG,
  159.     gs_color_space_index_CIEDEF,
  160.     gs_color_space_index_CIEABC,
  161.     gs_color_space_index_CIEA,
  162.     gs_color_space_index_Separation,
  163.     gs_color_space_index_Indexed,
  164.     gs_color_space_index_Pattern
  165.  
  166. } gs_color_space_index;
  167.  
  168. /* We define the names only for debugging printout. */
  169. #define GS_COLOR_SPACE_TYPE_NAMES\
  170.   "DeviceGray", "DeviceRGB", "DeviceCMYK", "DevicePixel", "DeviceN",\
  171.   "CIEBasedDEFG", "CIEBasedDEF", "CIEBasedABC", "CIEBasedA",\
  172.   "Separation", "Indexed", "Pattern"
  173.  
  174. /* Define an abstract type for color space types (method structures). */
  175. typedef struct gs_color_space_type_s gs_color_space_type;
  176.  
  177. /*
  178.  * The common part of all color spaces. This structure now includes a memory
  179.  * structure pointer, so that it may be released without providing this
  180.  * information separately. (type is a pointer to the structure of methods.)
  181.  *
  182.  * Note that all color space structures consist of the basic information and
  183.  * a union containing some additional information. The macro operand is that
  184.  * union.
  185.  */
  186. #define gs_cspace_common(param_union)   \
  187.     const gs_color_space_type * type;   \
  188.     gs_memory_t *               pmem;   \
  189.     gs_id                       id;     \
  190.     union {                             \
  191.     param_union;                    \
  192.     }                           params
  193.  
  194. /*
  195.  * Parameters for base color spaces. Of the base color spaces, only
  196.  * DevicePixel and CIE spaces have parameters: see gscie.h for the structure
  197.  * definitions for CIE space parameters.
  198.  */
  199. typedef struct gs_device_pixel_params_s {
  200.     int depth;
  201. } gs_device_pixel_params;
  202. typedef struct gs_cie_a_s gs_cie_a;
  203. typedef struct gs_cie_abc_s gs_cie_abc;
  204. typedef struct gs_cie_def_s gs_cie_def;
  205. typedef struct gs_cie_defg_s gs_cie_defg;
  206.  
  207. #define gs_base_cspace_params           \
  208.     gs_device_pixel_params   pixel;     \
  209.     gs_cie_defg *            defg;      \
  210.     gs_cie_def *             def;       \
  211.     gs_cie_abc *             abc;       \
  212.     gs_cie_a *               a
  213.  
  214. typedef struct gs_base_color_space_s {
  215.     gs_cspace_common(gs_base_cspace_params);
  216. } gs_base_color_space;
  217.  
  218. #define gs_base_color_space_size sizeof(gs_base_color_space)
  219.  
  220. /*
  221.  * Non-base direct color spaces: Separation and DeviceN spaces.
  222.  * These include a base alternative color space.
  223.  */
  224. typedef ulong gs_separation_name;    /* BOGUS */
  225. typedef struct gs_indexed_map_s gs_indexed_map;
  226.  
  227. typedef struct gs_separation_params_s {
  228.     gs_separation_name sname;
  229.     gs_base_color_space alt_space;
  230.     gs_indexed_map *map;
  231. } gs_separation_params;
  232.  
  233. #ifndef gs_device_n_map_DEFINED
  234. #  define gs_device_n_map_DEFINED
  235. typedef struct gs_device_n_map_s gs_device_n_map;
  236. #endif
  237. typedef struct gs_device_n_params_s {
  238.     gs_separation_name *names;
  239.     uint num_components;
  240.     gs_base_color_space alt_space;
  241.     gs_device_n_map *map;
  242. } gs_device_n_params;
  243.  
  244. #define gs_direct_cspace_params         \
  245.     gs_base_cspace_params;              \
  246.     gs_separation_params separation;    \
  247.     gs_device_n_params device_n
  248.  
  249. typedef struct gs_direct_color_space_s {
  250.     gs_cspace_common(gs_direct_cspace_params);
  251. } gs_direct_color_space;
  252.  
  253. #define gs_direct_color_space_size sizeof(gs_direct_color_space)
  254.  
  255. /*
  256.  * Non-direct paint space: Indexed space.
  257.  *
  258.  * Note that for indexed color spaces, hival is the highest support index,
  259.  * which is one less than the number of entries in the palette (as defined
  260.  * in PostScript).
  261.  */
  262.  
  263. typedef struct gs_indexed_params_s {
  264.     gs_direct_color_space base_space;
  265.     int hival;            /* num_entries - 1 */
  266.     union {
  267.     gs_const_string table;    /* size is implicit */
  268.     gs_indexed_map *map;
  269.     } lookup;
  270.     bool use_proc;        /* 0 = use table, 1 = use proc & map */
  271. } gs_indexed_params;
  272.  
  273. #define gs_paint_cspace_params          \
  274.     gs_direct_cspace_params;            \
  275.     gs_indexed_params indexed
  276.  
  277. typedef struct gs_paint_color_space_s {
  278.     gs_cspace_common(gs_paint_cspace_params);
  279. } gs_paint_color_space;
  280.  
  281. #define gs_paint_color_space_size sizeof(gs_paint_color_space)
  282.  
  283. /*
  284.  * Pattern parameter set. This may contain an instances of a paintable
  285.  * color space. The boolean indicates if this is the case.
  286.  */
  287. typedef struct gs_pattern_params_s {
  288.     bool has_base_space;
  289.     gs_paint_color_space base_space;
  290. } gs_pattern_params;
  291.  
  292. /*
  293.  * Fully general color spaces.
  294.  */
  295. struct gs_color_space_s {
  296.     gs_cspace_common(
  297.     gs_paint_cspace_params;
  298.     gs_pattern_params pattern
  299.     );
  300. };
  301.  
  302. #define gs_pattern_color_space_size sizeof(gs_color_space)
  303.  
  304. /*
  305.  * Define the abstract type for color space objects.
  306.  */
  307. #ifndef gs_color_space_DEFINED
  308. #  define gs_color_space_DEFINED
  309. typedef struct gs_color_space_s gs_color_space;
  310. #endif
  311.  
  312.                     /*extern_st(st_color_space); *//* in gxcspace.h */
  313. #define public_st_color_space()    /* in gscspace.c */  \
  314.     gs_public_st_composite( st_color_space,         \
  315.                             gs_color_space,         \
  316.                             "gs_color_space",       \
  317.                             color_space_enum_ptrs,  \
  318.                             color_space_reloc_ptrs  \
  319.                             )
  320.  
  321. #define st_color_space_max_ptrs 2    /* 1 base + 1 indexed */
  322.  
  323. /* ---------------- Procedures ---------------- */
  324.  
  325. /* ------ Create/copy/destroy ------ */
  326.  
  327. /*
  328.  * Note that many of the constructors take no parameters, and the
  329.  * remainder take only a few (CIE color spaces constructures take a
  330.  * client data pointer as an operand, the composite color space (Separation,
  331.  * Indexed, and Pattern) constructurs take the base space as an operand,
  332.  * and the Indexed color space constructors have a few additiona operands).
  333.  * This is done to conserve memory. If initialization values for all the
  334.  * color space parameters were provided to the constructors, these values
  335.  * would need to have some fairly generic format. Different clients gather
  336.  * this data in different forms, so they would need to allocate memory to
  337.  * convert it to the generic form, only to immediately release this memory
  338.  * once the construction is complete.
  339.  *
  340.  * The alternative approach employed here is to provide a number of access
  341.  * methods (macros) that return pointers to individual fields of the
  342.  * various color space structures. This requires exporting only fairly simple
  343.  * data structures, and so does not violate modularity too severely.
  344.  *
  345.  * NB: Of necessity, the macros provide access to modifiable structures. If
  346.  *     these structures are modified after the color space object is first
  347.  *     initialized, unpredictable and, most likely, undesirable results will
  348.  *     occur.
  349.  *
  350.  * The constructors return an integer, 0 on success and an
  351.  * error code on failure (gs_error_VMerror or gs_error_rangecheck).
  352.  *
  353.  * In parallel with the constructors, we provide initializers that assume
  354.  * the client has allocated the color space object (perhaps on the stack)
  355.  * and takes responsibility for freeing it.
  356.  */
  357.  
  358. extern int
  359.     gs_cspace_init_DeviceGray(P1(gs_color_space *pcs)),
  360.     gs_cspace_build_DeviceGray(P2(gs_color_space ** ppcspace,
  361.                   gs_memory_t * pmem)),
  362.     gs_cspace_init_DeviceRGB(P1(gs_color_space *pcs)),
  363.     gs_cspace_build_DeviceRGB(P2(gs_color_space ** ppcspace,
  364.                  gs_memory_t * pmem)),
  365.     gs_cspace_init_DeviceCMYK(P1(gs_color_space *pcs)),
  366.     gs_cspace_build_DeviceCMYK(P2(gs_color_space ** ppcspace,
  367.                   gs_memory_t * pmem));
  368.  
  369. /*
  370.  * We preallocate instances of the 3 device color spaces, and provide
  371.  * procedures that return them.  Note that gs_cspace_DeviceCMYK() is
  372.  * defined even if CMYK color support is not included in this configuration.
  373.  */
  374. #ifndef gs_imager_state_DEFINED
  375. #  define gs_imager_state_DEFINED
  376. typedef struct gs_imager_state_s gs_imager_state;
  377. #endif
  378.  
  379. const gs_color_space * gs_cspace_DeviceGray(P1(const gs_imager_state * pis));
  380. const gs_color_space * gs_cspace_DeviceRGB(P1(const gs_imager_state * pis));
  381. const gs_color_space * gs_cspace_DeviceCMYK(P1(const gs_imager_state * pis));
  382.  
  383. /* Copy a color space into one newly allocated by the caller. */
  384. void gs_cspace_init_from(P2(gs_color_space * pcsto,
  385.                 const gs_color_space * pcsfrom));
  386.  
  387. /* Assign a color space into a previously initialized one. */
  388. void gs_cspace_assign(P2(gs_color_space * pdest, const gs_color_space * psrc));
  389.  
  390. /* Prepare to free a color space. */
  391. void gs_cspace_release(P1(gs_color_space * pcs));
  392.  
  393. /* ------ Accessors ------ */
  394.  
  395. /* Get the index of a color space. */
  396. gs_color_space_index gs_color_space_get_index(P1(const gs_color_space *));
  397.  
  398. /* Get the number of components in a color space. */
  399. int gs_color_space_num_components(P1(const gs_color_space *));
  400.  
  401. /*
  402.  * Test whether two color spaces are equal.  Note that this test is
  403.  * conservative: if it returns true, the color spaces are definitely
  404.  * equal, while if it returns false, they might still be equivalent.
  405.  */
  406. bool gs_color_space_equal(P2(const gs_color_space *pcs1,
  407.                  const gs_color_space *pcs2));
  408.  
  409. /* Restrict a color to its legal range. */
  410. #ifndef gs_client_color_DEFINED
  411. #  define gs_client_color_DEFINED
  412. typedef struct gs_client_color_s gs_client_color;
  413. #endif
  414. void gs_color_space_restrict_color(P2(gs_client_color *,
  415.                       const gs_color_space *));
  416.  
  417. /*
  418.  * Get the base space of an Indexed or uncolored Pattern color space, or the
  419.  * alternate space of a Separation or DeviceN space.  Return NULL if the
  420.  * color space does not have a base/alternative color space.
  421.  */
  422. const gs_color_space *gs_cspace_base_space(P1(const gs_color_space * pcspace));
  423.  
  424. /* backwards compatibility */
  425. #define gs_color_space_indexed_base_space(pcspace)\
  426.     gs_cspace_base_space(pcspace)
  427.  
  428. #endif /* gscspace_INCLUDED */
  429.